Elasticsearch QueryString Query Syntax Notes

TLDR

• query_string is a Lucene-based query syntax suitable for rapid retrieval.
• English operators (AND, OR, NOT) must be capitalized.
• When performing multi-word searches on keyword fields or numeric/date/boolean fields, you must use double quotes or the OR operator; otherwise, the query will fail to return results because the input cannot be tokenized.
• Comparison operators (>, >=, <, <=) will cause errors when used with the fields parameter; use range query syntax ([x TO y]) instead.
• Date queries containing colons (such as standard ISO formats) must be enclosed in double quotes.
• Date fields do not support comparison operators; always use range query syntax.
• Parameter settings for fuzzy search (~) and proximity search (~N) will be overridden by specific values within the query string.
• Field boosting (^) and query-level boost parameters have different scopes; the former affects relative weights between fields, while the latter affects the weight of clauses in a compound query.

Basic API Structure

In tools like Elasticvue or Kibana Discover, query_string provides a more concise way to query than DSL.

{
  "query": {
    "query_string": {
      "query": "your query string here",
      "default_field": "content",
      "default_operator": "OR"
    }
  },
  "size": 10,
  "from": 0,
  "sort": []
}

Query Syntax and Field Type Limitations

When you encounter this issue: You often find that you cannot retrieve data when performing multi-word queries on keyword or numeric fields.

Elasticsearch employs different analysis strategies for different field types. query_string selects its processing method based on the target field type:

• text fields: Uses the standard analyzer, which tokenizes and converts text to lowercase.
• keyword fields: Keeps the string intact.
• numeric/date/boolean fields: Does not use an analyzer; indexes the raw value.

Field Type	Query String	Behavior Description
text	apple banana	Equivalent to apple OR banana
keyword	apple banana	No results (treated as a literal string match)
numeric/date	123 456	No results (not automatically split)

Solution: For keyword or numeric fields, use double quotes to specify the value explicitly or use the OR operator:

{
  "query": {
    "query_string": {
      "query": "\"apple\" \"banana\""
    }
  }
}

Range Queries and Comparison Operators

When you encounter this issue: Your query fails when you attempt to use the fields parameter in combination with comparison operators (e.g., price:>=10).

Comparison operators (>, >=, <, <=) cause errors when used with the fields array parameter.

Recommended approach: Use range query syntax ([x TO y]), which is fully compatible with the fields parameter.

{
  "query": {
    "query_string": {
      "query": "[10 TO *]",
      "fields": ["price"]
    }
  }
}

Date and Time Query Considerations

When you encounter this issue: When you use standard date formats (containing colons) or attempt to use comparison operators on date fields.

• Format limitations: Standard formats (e.g., 2023-01-15T08:30:00Z) contain colons and must be enclosed in double quotes, otherwise, parsing will fail.
• Comparison operator limitations: Date fields do not support comparison operators; using them will cause the query to fail or throw an error.

Correct approach: Always use range query syntax.

{
  "query": {
    "query_string": {
      "query": "timestamp:[2023-01-15T08:30:00Z TO *]"
    }
  }
}

Weight Control: Boost and Field Weighting

When you encounter this issue: When you need to adjust the sorting weight of search results.

• Field Boost: Use the ^ syntax. For example, title^3 means the base score of that field will be multiplied by 3.
• Query-level Boost: Use the boost parameter. Primarily used in should clauses within a bool query to adjust the relative importance of different query conditions.

Key differences:

• Field boosting acts on different fields within a single query.
• Query boost acts on different clauses within a compound query.
• If a query is used in isolation, the boost parameter has no effect on sorting.

Fuzzy Search and Proximity Search

When you encounter this issue: When you have configured global fuzziness or phrase_slop parameters but find that the search results do not meet expectations.

The purpose of the tilde ~ depends on its position:

• After a single word (fuzzy search): Handles spelling errors. The fuzziness parameter must be used in conjunction with ~ in the query string to take effect.
• After a phrase (proximity search): Handles word order and distance. phrase_slop controls the maximum number of positions words can be moved.

Important rule: Values explicitly set in the query string (e.g., apple~2) will override the global settings in the API parameters.

Change Log

• 2025-04-13 Initial documentation created.
• 2025-10-03
  • Refined phrasing and standardized terminology.
  • Corrected the explanation of date range query syntax (date fields do not support comparison operators; range query syntax should be used).
  • Corrected the omission regarding the base score of fields in weight calculations.
  • Added technical details.